<?php
/**
 * Copyright 2011  SURFfoundation
 * 
 * This file is part of ESCAPE.
 * 
 * ESCAPE is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * ESCAPE is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with ESCAPE.  If not, see <http://www.gnu.org/licenses/>.
 * 
 * For more information:
 * http://escapesurf.wordpress.com/
 * http://www.surffoundation.nl/
 * 
 * Contact: d.vierkant@utwente.nl
 * 
 * @license http://www.gnu.org/licenses/gpl.html GNU GPLv3
 */
?>
<?php
/**
 * Matcher
 * 
 * Performs the matching process, calling data sources to fetch blocks and a comparator for scoring.
 */
class entityresolution_Matcher
{
	/**
	 * Data sources
	 * @var array[int]entityresolution_DataSource
	 */
	protected $dataSources;
	
	/**
	 * Query entity factory
	 * @var entityresolution_EntityFactory
	 */
	protected $queryEntityFactory;
	
	/**
	 * Block entity factory
	 * @var entityresolution_EntityFactory
	 */
	protected $blockEntityFactory;
	
	/**
	 * Comparator
	 * @var entityresolution_Comparator
	 */
	protected $comparator;
	
	/**
	 * Create a matcher instance.
	 * @param array[int]entityresolution_DataSource $dataSources
	 * @param entityresolution_EntityFactory $queryEntityFactory
	 * @param entityresolution_EntityFactory $blockEntityFactory
	 * @param entityresolution_Comparator $comparator
	 */
	public function __construct($dataSources, $queryEntityFactory, $blockEntityFactory, $comparator)
	{
		$this->dataSources = $dataSources;
		$this->queryEntityFactory = $queryEntityFactory;
		$this->blockEntityFactory = $blockEntityFactory;
		$this->comparator = $comparator;
	}
	
	/**
	 * Find entities matching the RDF resource specified.
	 * @param simplerdf_RdfResource $rdfResource RDF resource
	 * @param string $subjectUri subject URI
	 * @param float $threshold threshold, only entries with difference scores equal to or lower than the threshold are returned (defaults to no threshold)
	 * @return entityresolution_Result Result
	 */
	public function findMatches($rdfDocument, $subjectUri, $threshold = null)
	{
		// create an entity for the query data
		$queryEntity = $this->queryEntityFactory->createEntity($rdfDocument, $subjectUri);
		
		// fetch blocks from the data sources
		$blocks = array();
		foreach($this->dataSources as $dataSource)
		{
			/* @var $dataSource entityresolution_DataSource */
			$blocks[] = $dataSource->getBlock($queryEntity, $this->blockEntityFactory);
		}
		
		// create a result set
		$result = new entityresolution_Result();
		foreach($blocks as $block)
		{
			/* @var $block entityresolution_Block */
			
			$blockEntries = $block->getEntries();
			foreach($blockEntries as $blockEntry)
			{
				/* @var $blockEntry entityresolution_BlockEntry */
				
				$blockEntity = $blockEntry->getEntity();
				
				// compare the entities if no score is available
				$score = $blockEntry->getScore();
				if($score === null)
				{
					$score = $this->comparator->compareEntities($queryEntity, $blockEntity);
				}
				
				// create a result entity
				if($score !== null)
				{
					if($threshold === null || $score <= $threshold)
					{
						$resultEntry = new entityresolution_ResultEntry();
						$resultEntry->setSubjectUri($blockEntity->getSubjectUri());
						$resultEntry->setData($blockEntity->getSourceData());
						$resultEntry->setScore($score);
						$result->addEntry($resultEntry);
					}
				}
			}
		}
		
		return $result;
	}
}